home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 4 / MacMania 4.toast / / Sound / SoundEffects 0.9.2 / SoundEffects Developer’s Kit / Writing SoundEffects Effects < prev   
Text File  |  1994-11-21  |  12KB  |  234 lines
  1. Writing SoundEffects effect modules
  2. ---------------------------------------------------------------------------------
  3. ©1994 Alberto Ricci <ricci@pmn.it> <fricci@polito.it>
  4.  
  5.  
  6. MODULE STRUCTURE
  7.  
  8. Your effect module file must be of type '√Eff' and creator '√SFx'. The √ symbol
  9. is obtained by typing option-v.
  10.  
  11. SoundEffects calls your module by passing it four parameters:
  12. - a message (OSType) specifying which action to perform.
  13. - information on the sound (ModParamsPtr).
  14. - pointers to 68000 callback routines (GluePtr).
  15. - pointers to PowerPC callback routines (GluePtr).
  16.  
  17. To simplify things, a file called “Glue.c” is included in the SoundEffects
  18. Developer’s Kit. You should add this file to your project, so you don’t need
  19. to handle all the messages yourself: just write your own effect(), settings()
  20. and about() routines, as explained below.
  21.  
  22. To make your life even easier, two “empty” effect projects (Symantec C 7.0 and
  23. Metrowerks CodeWarrior 1.1) are included. Just make a copy of, rename it, and
  24. insert your code where needed.
  25.  
  26.  
  27. BUILDING THE MODULE
  28.  
  29. If your module doesn’t need a custom About… dialog, and uses the standard
  30. resources (as described below under “About Window resources”), add the file
  31. “ModNoAbout.c” to your project.
  32.  
  33. If your module doesn’t have any parameters or doesn’t need to save any settings,
  34. add the file “ModNoSettings.c” to your project.
  35.  
  36. Definitions of the structures and constants used in this document can be found
  37. in the header file “Glue.h” distributed with the SoundEffects Developer’s Kit.
  38. This file also contains all the prototypes you’ll need.
  39.  
  40. The header file “Glue.h” is commented, so take a look at it for specific
  41. information.
  42.  
  43. If you use the supplied “Glue.c” file, you can also use global variables
  44. throughout your code.
  45.  
  46.  
  47. RESOURCES
  48.  
  49. •    effect code resources are of type 'EFCT'.
  50. •    put any error messages (which are reported with (*glue->ModShowError)() or by
  51.     returning a value ≠ noErr and ≠ kModCancel to the application) into a
  52.     'STR#' resource, ID = 1000.
  53. •    always put one 'mInf' resource, any ID. A template for this resource type is
  54.     included with the SoundEffects Developer’s Kit.
  55.     In this resource, specify the minimum amount of RAM you want available before
  56.     running and the oldest header version your effect supports (see below,
  57.     “Header Versions”).
  58.  
  59.  
  60. OPTIONAL RESOURCES
  61.  
  62. •    if you add a resource of type 'EFCF' to a module, and an FPU is present, that
  63.     code resource will be called instead of the 'EFCT' one, with the same parameters.
  64. •    if you add a resource of type 'EFCP' to a module, and SoundEffects is running
  65.     on a Power Mac, that code resource will be called instead of the 'EFCT' one,
  66.     with the same parameters.
  67. •    put any picture and/or text (shareware notices, author info, etc.) you want
  68.     to be displayed in the Progress window when the module is running into a
  69.     PICT and/or TEXT resource, ID = 1001.
  70. •    If you want your effect to appear in a submenu of the “Effects” menu in
  71.     SoundEffects, add a resource of type 'Grup', any ID, containing the name
  72.     of the submenu. The format of this resource is identical to that of a 'STR '
  73.     resource, and a template is included with the Developer’s Kit.
  74.  
  75.  
  76. ABOUT WINDOW RESOURCES
  77.  
  78. •    put any copyright info into a 'STR ' resource, ID = 1000, and it will be
  79.     displayed in the effect’s about dialog (shown when choosing the effect with
  80.     the shift key down).
  81. •    put a description of the effect into a 'TEXT' resource, ID = 1000, which will be
  82.     displayed in the effect’s about dialog.
  83. •    put any version info into a 'vers' resource, ID = 1, and it will be displayed in
  84.     the effect’s about dialog.
  85. •    if you want a custom window size for the about dialog, add a 'nrct' resource,
  86.     ID = 1000, containing the rect of the window in the first rectangle field.
  87. •    if you want to add a picture to the window, add it as a 'PICT' resource,
  88.     ID = 1000, and put the rect in which it should appear in the second rectangle
  89.     field in the 'nrct' resource, ID = 1000.
  90.     If you don’t add this rectangle to the 'nrct' resource, the picture’s rectangle
  91.     will be used.
  92.     If you add the rectangle to the 'nrct' resource, but it is empty (top = bottom
  93.     and left = right), the picture’s rectangle will be used, and the top left corner
  94.     will be positioned at the top left corner of the empty rectangle.
  95.  
  96.  
  97. HEADER VERSIONS
  98.  
  99. SoundEffects determines whether an effect module is compatible with it by looking
  100. at two version numbers the module supplies:
  101. - the version number of the header file the module was compiled with, and
  102. - the oldest version number of the header file the module requires.
  103.  
  104. For example, suppose the version of the headers you are using is version 10.
  105. In the headers file, it is specified which callbacks were introduced in which
  106. version.
  107. Let’s suppose in your module you don’t use any callbacks that were introduced in
  108. versions 8 or higher: all the callbacks you use are labeled as “Version 1...7
  109. Callbacks” in the header file. In this case, you’d specify 7 as the oldest supported
  110. headers version. This way, you tell SoundEffects that your module cannot run on
  111. versions of SoundEffects which do not support all the callbacks you use (in this
  112. case versions of SoundEffects that correspond to header versions 1 to 6).
  113.  
  114. You must specify the oldest version number of the header file in a 'mInf' resource,
  115. as described above in “Resources”.
  116.  
  117.  
  118. CALLBACKS
  119.  
  120. The pointers to the callback routines are passed to your module by SoundEffects in
  121. two parameters: glue68k and gluePPC. These two structures contain pointers to the
  122. same routines, but you will have to use glue68k if your code resource contains
  123. 680x0 code, and gluePPC if it contains native PowerPC code.
  124. If you use the file “Glue.c” supplied with the SoundEffects Developer’s Kit, this
  125. will be handled for you and your settings() and effect() routines will only receive
  126. the pointer to the one appropriate GlueRec structure.
  127.  
  128. In any case, you will always call the callbacks the same way:
  129. theResult = (*glue->TheCallback)(theParameters);
  130.  
  131. All the callbacks may move memory.
  132.  
  133. •    GetBytesToProcess        returns the number of selected bytes, taking into account
  134.                             every selected channel and its length.
  135. •    ModMaxChSize            returns the length (in bytes) of the longest channel.
  136. •    ModMaxRelChSize            takes the number of selected bytes in each channel
  137.                             and returns the greatest one.
  138. •    ModDoSettingsDialog        handles all the settings dialog automatically.
  139.                             Pass true in withSetups if you want to have a pop-up
  140.                             menu with common used settings in the dialog. Everything
  141.                             will be handled by this single callback.
  142.                             Pass an ItemInfoHandle containing a description of each
  143.                             dialog item to the callback.
  144.                             See the sample module “Settings Test” for details.
  145. •    ModGetSampleValueLimits    returns the maximum and minimum value allowed for a sample
  146.                             with the current bps value.
  147.  
  148.  
  149. PROGRESS BAR
  150.  
  151. • Call (*glue->ModSetupProgress)() early in your module to specify which string you
  152. want to display in the progress bar and to start animating the watch cursor.
  153. • pass it a pointer to a short variable. This variable MUST be either a global
  154. variable or one that won’t be disposed of before ModCloseProgress will be called.
  155. Whenever you have time in your loop, check the value of this variable: if it is not
  156. zero, you should call (*glue->ModShowProgress)().
  157. • Pass ModShowProgress two parameters to indicate at what point you are in process.
  158. For example, pass percentageDone and 100, or processedSamples and
  159. totalSamplesToProcess. Pass 0xFFFFFFFF in the first parameter if you can’t tell
  160. in which point you are of the effect process. In this case, a striped bar will
  161. be shown.
  162. Also pass it a pointer to the “timeToCallProgress” short variable. It will reset
  163. it to zero.
  164. • ModShowProgress returns a OSErr value. If the user clicks the Stop button, this
  165. value will be kModCancel, and the module should clean up and exit. If possible, it
  166. should restore the original data. If this can’t be done or is too much work, pass
  167. false in the canCancel parameter, otherwise pass true.
  168. • ALWAYS call (*glue->ModCloseProgress)() before exiting.
  169.  
  170. • If you don’t want to show a progress window, you can still call ModSetupProgress
  171. and then ModCloseProgress to show the spinning watch cursor.
  172.  
  173. • You can pass 0L to ModSetupProgress in the textStr or in the modInfo parameters,
  174. but not in the timeToCallProgress parameter.
  175.  
  176.  
  177. RECORDS, PARAMETERS AND VARIABLES
  178.  
  179. •    All selection bounds and sound sizes are passed in bytes, not samples.
  180.     If modInfo->selSt is 0L and modInfo->selEnd is 5000L, it means the first byte
  181.     you are allowed to touch is the one at (*myChannelHandle + 0L), and the last one
  182.     if (*myChannelHandle + 4999L), not the 5000th.
  183.     The number of selected bytes is, of course, modInfo->selEnd - modInfo->selSt, in
  184.     this case 5000.
  185. •    You can obtain the size of one sample, in bytes, with:
  186.     sampleSize = modInfo->bps/8 + (modInfo->bps%8 != 0);
  187. •    modInfo->firstSelCh and modInfo->lastSelCh values range from 1 to
  188.     modInfo->numChans.
  189. •    An SEChanHandle is passed to your module inside the ModParamsRec record. This
  190.     handle contains the handles to the document’s channels and their sizes.
  191.     The handle to channel number ch is, for example:
  192.     myChannelHandle = (*modInfo->hands)[channelNumber].chan;
  193.     and the size of that channel, in bytes, is:
  194.     myChannelSize = (*modInfo->hands)[channelNumber].size;
  195. •    The ModParamsRec should contain everything you need to know about the sound:
  196.     a pointer to the window (parentWind), the selection bounds (selSt, selEnd,
  197.     firstSelCh, lastSelCh), the number of channels (numChans), the sample size
  198.     (bps), the sampling rate (rate), the loop bounds (loopSt, loopEnd), the
  199.     currently selected units (units - see the file “ModUnits.h”).
  200. •    The doExtend field of the ModParamsRec record contains 1 if the user wants
  201.     you to enlarge the sound as necessary when your effect needs to do that;
  202.     0 if the user wants the selection to have the same length as before applying
  203.     the effect, or 2 if he wants to decide each time. So, if you’re going to
  204.     modify the length of the selection or if you may change the sound outside
  205.     the selection, and modInfo->doExtend is 2, call (*glue->AskDoExtend)().
  206.     This callback will return either true (extend) or false (don’t extend the
  207.     selection).
  208. •    The short integers returned by (*glue->ModGetChannelPan)() are formatted as
  209.     volumes in the new SoundManager 3.0. They are fixed-point values, where the
  210.     high byte is the integer part and the low byte is the fractional part.
  211.     0x0100 (kFullVolume)    is full volume (you can overdrive the channel by setting
  212.                             the value to more than 1.0),
  213.     0x0080                    is half volume, and
  214.     0x0000                    is silent.
  215.     All negative values are silent.
  216. •    The reference number for the module file is contained in the refNum field of
  217.     the ModParamsRec record, modInfo->refNum.
  218.  
  219.  
  220. RESULT CODES
  221.  
  222. When the module is called, it should perform only the requested action and then
  223. exit, returning a OSErr value. This value should be:
  224. - kModNoError            if the effect ran succesfully and some data was modified.
  225. - kModCancel            if the effect left everything untouched.
  226. - any positive value    if an error occurred and some data was modified.
  227.                         SoundEffects will take care of alerting the user about
  228.                         this, and it will use the corresponding string in the
  229.                         module’s 'STR#' resource, ID = 1000, as an error message.
  230. - any negative value    if an error occurred and nothing was changed.
  231.                         SoundEffects will use the corresponding positive string
  232.                         in the module’s 'STR#' resource, ID = 1000, as an error
  233.                         message.
  234.